.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string_view \- std::basic_string_view

.SH Synopsis
   Defined in header <string_view>
   template<

       class CharT,                            \fI(since C++17)\fP
       class Traits = std::char_traits<CharT>

   > class basic_string_view;

   The class template basic_string_view describes an object that can refer to a
   constant contiguous sequence of CharT with the first element of the sequence at
   position zero.

   For a basic_string_view str, pointers, iterators, and references to elements of str
   are invalidated when an operation invalidates a pointer in the range
   [str.data(), str.data() + str.size()).

   Every specialization of std::basic_string_view is a TriviallyCopyable  (since C++23)
   type.

   A typical implementation holds only two members: a pointer to constant CharT and a
   size.

   Several typedefs for common character types are provided:

   Defined in header <string_view>
   Type                        Definition
   std::string_view \fI(C++17)\fP    std::basic_string_view<char>
   std::wstring_view \fI(C++17)\fP   std::basic_string_view<wchar_t>
   std::u8string_view (C++20)  std::basic_string_view<char8_t>
   std::u16string_view \fI(C++17)\fP std::basic_string_view<char16_t>
   std::u32string_view \fI(C++17)\fP std::basic_string_view<char32_t>

.SH Template parameters

   CharT  - character type
            CharTraits class specifying the operations on the character type. Like for
   Traits - std::basic_string, Traits::char_type must name the same type as CharT or
            the program is ill-formed.

   Nested types

   Nested type            Definition
   traits_type            Traits
   value_type             CharT
   pointer                CharT*
   const_pointer          const CharT*
   reference              CharT&
   const_reference        const CharT&
                          implementation-defined constant LegacyRandomAccessIterator,

   const_iterator         and LegacyContiguousIterator               \fI(until C++20)\fP
                          ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP

                          whose value_type is CharT
   iterator               const_iterator
   const_reverse_iterator std::reverse_iterator<const_iterator>
   reverse_iterator       const_reverse_iterator
   size_type              std::size_t
   difference_type        std::ptrdiff_t

   Note: iterator and const_iterator are the same type because string views are views
   into constant character sequences.

   All requirements on the iterator types of a Container applies to the iterator and
   const_iterator types of basic_string_view as well.

.SH Member functions

         Constructors and assignment
   constructor       constructs a basic_string_view
                     \fI(public member function)\fP
   operator=         assigns a view
                     \fI(public member function)\fP
.SH Iterators
   begin             returns an iterator to the beginning
   cbegin            \fI(public member function)\fP
   end               returns an iterator to the end
   cend              \fI(public member function)\fP
   rbegin            returns a reverse iterator to the beginning
   crbegin           \fI(public member function)\fP
   rend              returns a reverse iterator to the end
   crend             \fI(public member function)\fP
.SH Element access
   operator[]        accesses the specified character
                     \fI(public member function)\fP
   at                accesses the specified character with bounds checking
                     \fI(public member function)\fP
   front             accesses the first character
                     \fI(public member function)\fP
   back              accesses the last character
                     \fI(public member function)\fP
   data              returns a pointer to the first character of a view
                     \fI(public member function)\fP
.SH Capacity
   size              returns the number of characters
   length            \fI(public member function)\fP
   max_size          returns the maximum number of characters
                     \fI(public member function)\fP
   empty             checks whether the view is empty
                     \fI(public member function)\fP
.SH Modifiers
   remove_prefix     shrinks the view by moving its start forward
                     \fI(public member function)\fP
   remove_suffix     shrinks the view by moving its end backward
                     \fI(public member function)\fP
   swap              swaps the contents
                     \fI(public member function)\fP
.SH Operations
   copy              copies characters
                     \fI(public member function)\fP
   substr            returns a substring
                     \fI(public member function)\fP
   compare           compares two views
                     \fI(public member function)\fP
   starts_with       checks if the string view starts with the given prefix
   (C++20)           \fI(public member function)\fP
   ends_with         checks if the string view ends with the given suffix
   (C++20)           \fI(public member function)\fP
   contains          checks if the string view contains the given substring or
   (C++23)           character
                     \fI(public member function)\fP
   find              find characters in the view
                     \fI(public member function)\fP
   rfind             find the last occurrence of a substring
                     \fI(public member function)\fP
   find_first_of     find first occurrence of characters
                     \fI(public member function)\fP
   find_last_of      find last occurrence of characters
                     \fI(public member function)\fP
   find_first_not_of find first absence of characters
                     \fI(public member function)\fP
   find_last_not_of  find last absence of characters
                     \fI(public member function)\fP
.SH Constants
   npos              special value. The exact meaning depends on the context
   \fB[static]\fP          \fI(public static member constant)\fP

.SH Non-member functions

   operator==
   operator!=
   operator<
   operator>
   operator<=
   operator>=
   operator<=>        lexicographically compares two string views
   \fI(C++17)\fP            \fI(function template)\fP
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (C++20)
.SH Input/output
   operator<<         performs stream output on string views
   \fI(C++17)\fP            \fI(function template)\fP

.SH Literals

   Defined in inline namespace std::literals::string_view_literals
   operator""sv    creates a string view of a character array literal
   \fI(C++17)\fP         \fI(function)\fP

.SH Helper classes

   std::hash<std::string_view>
   std::hash<std::wstring_view>
   std::hash<std::u8string_view>
   std::hash<std::u16string_view>
   std::hash<std::u32string_view> hash support for string views
   \fI(C++17)\fP                        \fI(class template specialization)\fP
   \fI(C++17)\fP
   (C++20)
   \fI(C++17)\fP
   \fI(C++17)\fP

   Helper templates

   template< class CharT, class Traits >

   inline constexpr bool                                                        (since
                                                                                C++20)
       ranges::enable_borrowed_range<std::basic_string_view<CharT, Traits>> =
   true;

   This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy
   borrowed_range.

   template< class CharT, class Traits >

   inline constexpr bool                                                  \fI(since C++20)\fP

       ranges::enable_view<std::basic_string_view<CharT, Traits>> =
   true;

   This specialization of ranges::enable_view makes basic_string_view satisfy view.

     Deduction guides \fI(since C++20)\fP

.SH Notes

   It is the programmer's responsibility to ensure that std::string_view does not
   outlive the pointed-to character array:

 std::string_view good{"a string literal"};
     // "Good" case: `good` points to a static array.
     // String literals reside in persistent data storage.

 std::string_view bad{"a temporary string"s};
     // "Bad" case: `bad` holds a dangling pointer since the std::string temporary,
     // created by std::operator""s, will be destroyed at the end of the statement.

   Specializations of std::basic_string_view are already trivially copyable types in
   all existing implementations, even before the formal requirement introduced in
   C++23.

      Feature-test macro      Value    Std        Feature
   __cpp_lib_string_view     201606L \fI(C++17)\fP std::string_view
                             201803L (C++20) ConstexprIterator
   __cpp_lib_string_contains 202011L (C++23) contains

.SH Example


// Run this code

 #include <iostream>
 #include <string_view>

 int main()
 {
     constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"};

     for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4))
     {
         for (int x{}; x != 16; ++x)
             std::cout << unicode[p];
         std::cout << '\\n';
     }
 }

.SH Output:

 ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─
 ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─
 ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄
 ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀
 ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─
 ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to        Behavior as published              Correct behavior
                       only pointers, iterators, and       all pointers, iterators, and
                       references                          references
   LWG 3203 C++17      returned from the member functions  to elements of
                       of                                  basic_string_view
                       basic_string_view might be          may be invalidated
                       invalidated

.SH See also

   basic_string     stores and manipulates sequences of characters
                    \fI(class template)\fP
   span             a non-owning view over a contiguous sequence of objects
   (C++20)          \fI(class template)\fP
   initializer_list creates a temporary array in list-initialization and then
   \fI(C++11)\fP          references it
                    \fI(class template)\fP
